home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / lib / mozilla-firefox / include / plugin / npruntime.h < prev    next >
C/C++ Source or Header  |  2006-05-08  |  16KB  |  398 lines
  1. /* -*- Mode: C; tab-width: 4; indent-tabs-mode: nil; c-basic-offset: 4 -*- */
  2. /*
  3.  * Copyright ⌐ 2004, Apple Computer, Inc. and The Mozilla Foundation. 
  4.  * All rights reserved.
  5.  * 
  6.  * Redistribution and use in source and binary forms, with or without
  7.  * modification, are permitted provided that the following conditions are
  8.  * met:
  9.  * 
  10.  * 1. Redistributions of source code must retain the above copyright
  11.  * notice, this list of conditions and the following disclaimer.
  12.  * 2. Redistributions in binary form must reproduce the above copyright
  13.  * notice, this list of conditions and the following disclaimer in the
  14.  * documentation and/or other materials provided with the distribution.
  15.  * 3. Neither the names of Apple Computer, Inc. ("Apple") or The Mozilla
  16.  * Foundation ("Mozilla") nor the names of their contributors may be used
  17.  * to endorse or promote products derived from this software without
  18.  * specific prior written permission.
  19.  * 
  20.  * THIS SOFTWARE IS PROVIDED BY APPLE, MOZILLA AND THEIR CONTRIBUTORS "AS
  21.  * IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  22.  * TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
  23.  * PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL APPLE, MOZILLA OR
  24.  * THEIR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  25.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
  26.  * TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
  27.  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
  28.  * LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
  29.  * NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
  30.  * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  31.  *
  32.  * Revision 1 (March 4, 2004):
  33.  * Initial proposal.
  34.  *
  35.  * Revision 2 (March 10, 2004):
  36.  * All calls into script were made asynchronous.  Results are
  37.  * provided via the NPScriptResultFunctionPtr callback.
  38.  *
  39.  * Revision 3 (March 10, 2004):
  40.  * Corrected comments to not refer to class retain/release FunctionPtrs.
  41.  *
  42.  * Revision 4 (March 11, 2004):
  43.  * Added additional convenience NPN_SetExceptionWithUTF8().
  44.  * Changed NPHasPropertyFunctionPtr and NPHasMethodFunctionPtr to take NPClass
  45.  * pointers instead of NPObject pointers.
  46.  * Added NPIsValidIdentifier().
  47.  *
  48.  * Revision 5 (March 17, 2004):
  49.  * Added context parameter to result callbacks from ScriptObject functions.
  50.  *
  51.  * Revision 6 (March 29, 2004):
  52.  * Renamed functions implemented by user agent to NPN_*.  Removed _ from
  53.  * type names.
  54.  * Renamed "JavaScript" types to "Script".
  55.  *
  56.  * Revision 7 (April 21, 2004):
  57.  * NPIdentifier becomes a void*, was int32_t
  58.  * Remove NP_IsValidIdentifier, renamed NP_IdentifierFromUTF8 to NP_GetIdentifier
  59.  * Added NPVariant and modified functions to use this new type.
  60.  *
  61.  * Revision 8 (July 9, 2004):
  62.  * Updated to joint Apple-Mozilla license.
  63.  *
  64.  */
  65. #ifndef _NP_RUNTIME_H_
  66. #define _NP_RUNTIME_H_
  67.  
  68. #ifdef __cplusplus
  69. extern "C" {
  70. #endif
  71.  
  72. #include "nptypes.h"
  73.  
  74. /*
  75.     This API is used to facilitate binding code written in C to script
  76.     objects.  The API in this header does not assume the presence of a
  77.     user agent.  That is, it can be used to bind C code to scripting
  78.     environments outside of the context of a user agent.
  79.     
  80.     However, the normal use of the this API is in the context of a
  81.     scripting environment running in a browser or other user agent.
  82.     In particular it is used to support the extended Netscape
  83.     script-ability API for plugins (NP-SAP).  NP-SAP is an extension
  84.     of the Netscape plugin API.  As such we have adopted the use of
  85.     the "NP" prefix for this API.
  86.  
  87.     The following NP{N|P}Variables were added to the Netscape plugin
  88.     API (in npapi.h):
  89.  
  90.     NPNVWindowNPObject
  91.     NPNVPluginElementNPObject
  92.     NPPVpluginScriptableNPObject
  93.  
  94.     These variables are exposed through NPN_GetValue() and
  95.     NPP_GetValue() (respectively) and are used to establish the
  96.     initial binding between the user agent and native code.  The DOM
  97.     objects in the user agent can be examined and manipulated using
  98.     the NPN_ functions that operate on NPObjects described in this
  99.     header.
  100.  
  101.     To the extent possible the assumptions about the scripting
  102.     language used by the scripting environment have been minimized.
  103. */
  104.  
  105. #define NP_BEGIN_MACRO  do {
  106. #define NP_END_MACRO    } while (0)
  107.  
  108. /*
  109.     Objects (non-primitive data) passed between 'C' and script is
  110.     always wrapped in an NPObject.  The 'interface' of an NPObject is
  111.     described by an NPClass.
  112. */
  113. typedef struct NPObject NPObject;
  114. typedef struct NPClass NPClass;
  115.  
  116. typedef char NPUTF8;
  117. typedef struct _NPString {
  118.     const NPUTF8 *utf8characters;
  119.     uint32_t utf8length;
  120. } NPString;
  121.  
  122. typedef enum {
  123.     NPVariantType_Void,
  124.     NPVariantType_Null,
  125.     NPVariantType_Bool,
  126.     NPVariantType_Int32,
  127.     NPVariantType_Double,
  128.     NPVariantType_String,
  129.     NPVariantType_Object
  130. } NPVariantType;
  131.  
  132. typedef struct _NPVariant {
  133.     NPVariantType type;
  134.     union {
  135.         bool boolValue;
  136.         uint32_t intValue;
  137.         double doubleValue;
  138.         NPString stringValue;
  139.         NPObject *objectValue;
  140.     } value;
  141. } NPVariant;
  142.  
  143. /*
  144.     NPN_ReleaseVariantValue is called on all 'out' parameters
  145.     references.  Specifically it is to be called on variants that own
  146.     their value, as is the case with all non-const NPVariant*
  147.     arguments after a successful call to any methods (except this one)
  148.     in this API.
  149.  
  150.     After calling NPN_ReleaseVariantValue, the type of the variant
  151.     will be NPVariantType_Void.
  152. */
  153. void NPN_ReleaseVariantValue(NPVariant *variant);
  154.  
  155. #define NPVARIANT_IS_VOID(_v)    ((_v).type == NPVariantType_Void)
  156. #define NPVARIANT_IS_NULL(_v)    ((_v).type == NPVariantType_Null)
  157. #define NPVARIANT_IS_BOOLEAN(_v) ((_v).type == NPVariantType_Bool)
  158. #define NPVARIANT_IS_INT32(_v)   ((_v).type == NPVariantType_Int32)
  159. #define NPVARIANT_IS_DOUBLE(_v)  ((_v).type == NPVariantType_Double)
  160. #define NPVARIANT_IS_STRING(_v)  ((_v).type == NPVariantType_String)
  161. #define NPVARIANT_IS_OBJECT(_v)  ((_v).type == NPVariantType_Object)
  162.  
  163. #define NPVARIANT_TO_BOOLEAN(_v) ((_v).value.boolValue)
  164. #define NPVARIANT_TO_INT32(_v)   ((_v).value.intValue)
  165. #define NPVARIANT_TO_DOUBLE(_v)  ((_v).value.doubleValue)
  166. #define NPVARIANT_TO_STRING(_v)  ((_v).value.stringValue)
  167. #define NPVARIANT_TO_OBJECT(_v)  ((_v).value.objectValue)
  168.  
  169. #define VOID_TO_NPVARIANT(_v)                                                 \
  170. NP_BEGIN_MACRO                                                                \
  171.     (_v).type = NPVariantType_Void;                                           \
  172.     (_v).value.objectValue = NULL;                                            \
  173. NP_END_MACRO
  174.  
  175. #define NULL_TO_NPVARIANT(_v)                                                 \
  176. NP_BEGIN_MACRO                                                                \
  177.     (_v).type = NPVariantType_Null;                                           \
  178.     (_v).value.objectValue = NULL;                                            \
  179. NP_END_MACRO
  180.  
  181. #define BOOLEAN_TO_NPVARIANT(_val, _v)                                        \
  182. NP_BEGIN_MACRO                                                                \
  183.     (_v).type = NPVariantType_Bool;                                           \
  184.     (_v).value.boolValue = !!(_val);                                          \
  185. NP_END_MACRO
  186.  
  187. #define INT32_TO_NPVARIANT(_val, _v)                                          \
  188. NP_BEGIN_MACRO                                                                \
  189.     (_v).type = NPVariantType_Int32;                                          \
  190.     (_v).value.intValue = _val;                                               \
  191. NP_END_MACRO
  192.  
  193. #define DOUBLE_TO_NPVARIANT(_val, _v)                                         \
  194. NP_BEGIN_MACRO                                                                \
  195.     (_v).type = NPVariantType_Double;                                         \
  196.     (_v).value.doubleValue = _val;                                            \
  197. NP_END_MACRO
  198.  
  199. #define STRINGZ_TO_NPVARIANT(_val, _v)                                        \
  200. NP_BEGIN_MACRO                                                                \
  201.     (_v).type = NPVariantType_String;                                         \
  202.     NPString str = { _val, strlen(_val) };                                    \
  203.     (_v).value.stringValue = str;                                             \
  204. NP_END_MACRO
  205.  
  206. #define STRINGN_TO_NPVARIANT(_val, _len, _v)                                  \
  207. NP_BEGIN_MACRO                                                                \
  208.     (_v).type = NPVariantType_String;                                         \
  209.     NPString str = { _val, _len };                                            \
  210.     (_v).value.stringValue = str;                                             \
  211. NP_END_MACRO
  212.  
  213. #define OBJECT_TO_NPVARIANT(_val, _v)                                         \
  214. NP_BEGIN_MACRO                                                                \
  215.     (_v).type = NPVariantType_Object;                                         \
  216.     (_v).value.objectValue = _val;                                            \
  217. NP_END_MACRO
  218.  
  219.  
  220. /*
  221.     Type mappings (JavaScript types have been used for illustration
  222.     purposes):
  223.  
  224.     JavaScript       to             C (NPVariant with type:)
  225.     undefined                       NPVariantType_Void
  226.     null                            NPVariantType_Null
  227.     Boolean                         NPVariantType_Bool
  228.     Number                          NPVariantType_Double or NPVariantType_Int32
  229.     String                          NPVariantType_String
  230.     Object                          NPVariantType_Object
  231.  
  232.     C (NPVariant with type:)   to   JavaScript
  233.     NPVariantType_Void              undefined
  234.     NPVariantType_Null              null
  235.     NPVariantType_Bool              Boolean    
  236.     NPVariantType_Int32             Number
  237.     NPVariantType_Double            Number
  238.     NPVariantType_String            String
  239.     NPVariantType_Object            Object
  240. */
  241.  
  242. typedef void *NPIdentifier;
  243.  
  244. /*
  245.     NPObjects have methods and properties.  Methods and properties are
  246.     identified with NPIdentifiers.  These identifiers may be reflected
  247.     in script.  NPIdentifiers can be either strings or integers, IOW,
  248.     methods and properties can be identified by either strings or
  249.     integers (i.e. foo["bar"] vs foo[1]). NPIdentifiers can be
  250.     compared using ==.  In case of any errors, the requested
  251.     NPIdentifier(s) will be NULL.
  252. */
  253. NPIdentifier NPN_GetStringIdentifier(const NPUTF8 *name);
  254. void NPN_GetStringIdentifiers(const NPUTF8 **names, int32_t nameCount,
  255.                               NPIdentifier *identifiers);
  256. NPIdentifier NPN_GetIntIdentifier(int32_t intid);
  257. bool NPN_IdentifierIsString(NPIdentifier identifier);
  258.  
  259. /*
  260.     The NPUTF8 returned from NPN_UTF8FromIdentifier SHOULD be freed.
  261. */
  262. NPUTF8 *NPN_UTF8FromIdentifier(NPIdentifier identifier);
  263.  
  264. /*
  265.     Get the integer represented by identifier. If identifier is not an
  266.     integer identifier, the behaviour is undefined.
  267. */
  268. int32_t NPN_IntFromIdentifier(NPIdentifier identifier);
  269.  
  270. /*
  271.     NPObject behavior is implemented using the following set of
  272.     callback functions.
  273.  
  274.     The NPVariant *result argument of these functions (where
  275.     applicable) should be released using NPN_ReleaseVariantValue().
  276. */
  277. typedef NPObject *(*NPAllocateFunctionPtr)(NPP npp, NPClass *aClass);
  278. typedef void (*NPDeallocateFunctionPtr)(NPObject *npobj);
  279. typedef void (*NPInvalidateFunctionPtr)(NPObject *npobj);
  280. typedef bool (*NPHasMethodFunctionPtr)(NPObject *npobj, NPIdentifier name);
  281. typedef bool (*NPInvokeFunctionPtr)(NPObject *npobj, NPIdentifier name,
  282.                                     const NPVariant *args, uint32_t argCount,
  283.                                     NPVariant *result);
  284. typedef bool (*NPInvokeDefaultFunctionPtr)(NPObject *npobj,
  285.                                            const NPVariant *args,
  286.                                            uint32_t argCount,
  287.                                            NPVariant *result);
  288. typedef bool (*NPHasPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name);
  289. typedef bool (*NPGetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
  290.                                          NPVariant *result);
  291. typedef bool (*NPSetPropertyFunctionPtr)(NPObject *npobj, NPIdentifier name,
  292.                                          const NPVariant *value);
  293. typedef bool (*NPRemovePropertyFunctionPtr)(NPObject *npobj,
  294.                                             NPIdentifier name);
  295.  
  296. /*
  297.     NPObjects returned by create, retain, invoke, and getProperty pass
  298.     a reference count to the caller.  That is, the callee adds a
  299.     reference count which passes to the caller.  It is the caller's
  300.     responsibility to release the returned object.
  301.  
  302.     NPInvokeFunctionPtr function may return 0 to indicate a void
  303.     result.
  304.  
  305.     NPInvalidateFunctionPtr is called by the scripting environment
  306.     when the native code is shutdown.  Any attempt to message a
  307.     NPObject instance after the invalidate callback has been
  308.     called will result in undefined behavior, even if the native code
  309.     is still retaining those NPObject instances.  (The runtime
  310.     will typically return immediately, with 0 or NULL, from an attempt
  311.     to dispatch to a NPObject, but this behavior should not be
  312.     depended upon.)
  313. */
  314. struct NPClass
  315. {
  316.     uint32_t structVersion;
  317.     NPAllocateFunctionPtr allocate;
  318.     NPDeallocateFunctionPtr deallocate;
  319.     NPInvalidateFunctionPtr invalidate;
  320.     NPHasMethodFunctionPtr hasMethod;
  321.     NPInvokeFunctionPtr invoke;
  322.     NPInvokeDefaultFunctionPtr invokeDefault;
  323.     NPHasPropertyFunctionPtr hasProperty;
  324.     NPGetPropertyFunctionPtr getProperty;
  325.     NPSetPropertyFunctionPtr setProperty;
  326.     NPRemovePropertyFunctionPtr removeProperty;
  327. };
  328.  
  329. #define NP_CLASS_STRUCT_VERSION 1
  330.  
  331. struct NPObject {
  332.     NPClass *_class;
  333.     uint32_t referenceCount;
  334.     /*
  335.      * Additional space may be allocated here by types of NPObjects
  336.      */
  337. };
  338.  
  339. /*
  340.     If the class has an allocate function, NPN_CreateObject invokes
  341.     that function, otherwise a NPObject is allocated and
  342.     returned. This method will initialize the referenceCount member of
  343.     the NPObject to 1.
  344. */
  345. NPObject *NPN_CreateObject(NPP npp, NPClass *aClass);
  346.  
  347. /*
  348.     Increment the NPObject's reference count.
  349. */
  350. NPObject *NPN_RetainObject(NPObject *npobj);
  351.  
  352. /*
  353.     Decremented the NPObject's reference count.  If the reference
  354.     count goes to zero, the class's destroy function is invoke if
  355.     specified, otherwise the object is freed directly.
  356. */
  357. void NPN_ReleaseObject(NPObject *npobj);
  358.  
  359. /*
  360.     Functions to access script objects represented by NPObject.
  361.  
  362.     Calls to script objects are synchronous.  If a function returns a
  363.     value, it will be supplied via the result NPVariant
  364.     argument. Successful calls will return true, false will be
  365.     returned in case of an error.
  366.     
  367.     Calls made from plugin code to script must be made from the thread
  368.     on which the plugin was initialized.
  369. */
  370.  
  371. bool NPN_Invoke(NPP npp, NPObject *npobj, NPIdentifier methodName,
  372.                 const NPVariant *args, uint32_t argCount, NPVariant *result);
  373. bool NPN_InvokeDefault(NPP npp, NPObject *npobj, const NPVariant *args,
  374.                        uint32_t argCount, NPVariant *result);
  375. bool NPN_Evaluate(NPP npp, NPObject *npobj, NPString *script,
  376.                   NPVariant *result);
  377. bool NPN_GetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
  378.                      NPVariant *result);
  379. bool NPN_SetProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName,
  380.                      const NPVariant *value);
  381. bool NPN_RemoveProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
  382. bool NPN_HasProperty(NPP npp, NPObject *npobj, NPIdentifier propertyName);
  383. bool NPN_HasMethod(NPP npp, NPObject *npobj, NPIdentifier methodName);
  384.  
  385. /*
  386.     NPN_SetException may be called to trigger a script exception upon
  387.     return from entry points into NPObjects.  Typical usage:
  388.  
  389.     NPN_SetException (npobj, message);
  390. */
  391. void NPN_SetException(NPObject *npobj, const NPUTF8 *message);
  392.  
  393. #ifdef __cplusplus
  394. }
  395. #endif
  396.  
  397. #endif
  398.